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PREFACE 



This publication is intended for APLSV users and application 
programmers . It complements the description of APL given in the APL 
Language Manual (GC26-3847) , and describes the TSIO auxiliary 
processor , a program which gives the user at an APL terminal interactive 
control of OS/VS Data Management facilities through Shared Variables. 

This publication consists of the following sections: 

Use of APL - Describes APL features particular to the APLSV system 
such as: number and character representations; values of system 
variables; bounds on the lengths of names and on the ranks of 
arrays ; and additional system commands . 

Use of TSIO Auxiliary Processor - Describes the auxiliary processor 
that provides for interactive use of many of the data management 
facilities of the OS/VS. Operating System by the APL user. In order 
to take full advantage of all the facilities of the TSIO Auxiliary 
Processor, users may require further information on OS/VS data 
management. This information may be found in the publication OS/VS 
Data Management Services Guide (GC26-3783) . In addition, the 
following publications should be consulted for information specific 
to the OS/VS operating system being used: 

OS/VS 1 JCL Reference (GC24-5099) 

OS/VS 2 JCL (GC28-0692) 

Additional information about the use of magnetic tape can be found in 
the publications: 

System/360 Component Description 2400 - Series Magnetic Tape Units 
(GA22-6866) . 

3803 / 3420 Magnetic Tape Subsystems Component Description (GA32-0020) . 

Use of Distributed Workspaces - Summarizes the contents and the 
application of the workspaces distributed with APLSV. 
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SECTION 1 : INTRODUCTION 

The APL Shared Variable (APLSV) system is a program which runs on 
an IBM System/370 computer under one of the IBM Operating Systems 0S/VS1 
or 0S/VS2. It provides facilities for the execution of programs written 
in APL and for communication between APL programs and other subsystems 
by means of shared variables . The program consists of: 

o An APL Interpreter which executes the APL Language described in 
the APL Language Manual, GC26-3847 

o An APLSV supervisor, which maps host-independent service requests 
made by the APL interpreter into calls for OS/VS system services, 
and distributes the central computer resources allocated to APLSV 
among the current APL users . 

° The Shared Variable Processor, which provides the host 

independent services necessary to implement shared variables as 
described in the APL Language Manual. These services are 
available both to the APL programmer and to the system programmer 
who wishes to permit access from APLSV to portions of the 
computer system external to the APLSV facility. 

° The Time Shared Input/Output (TSIO) auxiliary processor, which 
accepts commands through shared variables and permits users at 
APL terminals interactive control of standard OS/VS operating 
system data management facilities. 

« A library management facility, used to make copies on tape of 

workspaces saved in APL libraries, either for archival storage or 
for export to other systems. 
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SECTION 2: USE OF APL 



ACCESS TO THE SYSTEM 



Each user of the APLSV system is assigned, by a system manager, an 
account number used to identify his data on external storage and his 
charges for use of the system. This account number is required in 
order for the user to sign on . 

Once a connection to the computer has been established any input 
I other than a sign-on is rejected with the report INCORRECT SIGN-ON. 

The sign-on command consists of a right parenthesis followed by an 
account number, a colon, and a password, for example: 

)8d88:AGBDF 

Note that the APL right parenthesis and the APL colon, whose positions 
are given in the APL Language manual, must be used. The system manager 
assigns an initial password. The user should change his password 
frequently. 

Successful sign-on is acknowledged by a message showing the port 

number, the date and time, the user's name, and the system 

identification. This may be preceded by a broadcast message from the 
system operator. 

At sign-on, the accumulation of time charges begins. A clear 
workspace is activated, except in the case that the preceding session 
was terminated by the command ) CONTINUE resulting in the saving of an 
unlocked CONTINUE workspace. In that case, the workspace CONTINUE is 
activated and its latent expression executed. 

An attempt to sign-on may be rejected, with one of the following 
reports : 

I INCORRECT COMMAND: The terminal is in use, and must first be signed off 
before a new sign-on can be accepted. 

NUMBER. IN USE: The indicated account number is in use at another port. 
This may arise either because another user is in fact using the account, 
or occasionally (perhaps because of an equipment problem) because the 
system did not complete disconnection at an earlier work session. 

NUMBER LOCKED OUT: While the indicated account number and password are 
valid, authorization for use of the account has been withdrawn. This 
also prevents workspaces stored in the library of this account from 
being loaded or copied by other users. 

REPRESENTATION OF DATA 

CHARACTERS 

The elements of the system variable QAV are represented in APLSV 
as 8 bit bytes. The correspondence between the base 2 values of the 
bytes (0-origin indices to QAV) and the APLSV characters, shown in 
Figure 1, was chosen to simplify implementation matters (for example, 
the letters are grouped together so that the test for alphabetic is 
performed with two comparisons) . Certain elements of QAV cause special 
actions , as their names in Figure 1 indicate , when transmitted to 
I certain terminals. Elements 1 to 1 3 and 168 to 255 have no visible 
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effect on display. Functions that index UAV to generate specific 
characters may require modification for transfer to other APL systems. 

NUMBERS 

A number may be represented in an APLSV workspace as 8-byte 
floating-point, 4-byte integer, or 1-bit boolean. 

Any number between [/ i0«-+~7 . 237S75 and L/ iO-m-7 . 237575 may be 
represented as floating-point. If the number is integral of magnitude 
less than 2*31 it may also be represented as an integer. Finally, if it 
is either or 1 , it may in addition be represented as boolean. 



Non-integers or integers of magnitudes exceeding 
represented as floating-point. 



1+2*31 are 



The way a number is represented in the workspace depends on the 
way it was entered or which primitive function computed it. For 
example, if A>0*0 1 , then X and IX and l-X have the same value 1 , 
are represented in floating point, integral, and boolean forms, 
respectively. 



but 



Numbers may be entered or displayed in decimal or scaled forms . 
Display form may be explicitly controlled by the use of the dyadic 
format function. If not specified by the user, the form chosen for the 
display depends on the representation of the number in the workspace. 
Numbers stored as integers are displayed in decimal form, and their 
display is independent of the setting of the printing precision DPP. On 
the other hand, the display of numbers stored in floating-point is 
dependent on DPP. These are displayed either in scaled form, or, 
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Figure 1 : Atomic Vector (QAV) 
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provided they fall within the range from io*~4 to 10*QPP, in decimal 
form. 

For example: 

QPP+5 

L 1+2*31 
2147483647 

L2*31 
2. 147 5£9 

.0001 

. 1 

.00001 
IE 5 

Iff 4 
10000 

lff5 
1E5 

ARRAYS 

An array 4 occupies a sequence of adjacent words in the workspace. 
These words contain, in particular, the rank of A, its size, and its 
elements in row-major order. The number of words (4 bytes) required to 
store an array A is given by the expression: 

3+(ppA)+ryxx/pi4 

where T is 2, 1, .25 or .03125 according to whether the elements of A 
are represented in floating-point, integer, character or Boolean form, 
respectively. The maximum rank of an array is 64. Every element of the 
array is of the same type. 

If A is a numeric array of rank no less than 2, and has some 
element that would normally be displayed in scaled form, then the entire 
array A is displayed in scaled form. In addition, if any pair of 
elements of A differ by 10*4 or more in magnitude, then A is displayed 
in scaled form. If the length of the display of a vector, or of a row 
of a higher dimensional array, exceeds the printing width QPW , the 
display is continued on subsequent lines, each indented by 6 positions. 

SCANS OF ASSOCIATIVE FUNCTIONS 

For any dyadic function a and any vector X, the g- scan of X 
(denoted by a\X) yields a result Ft of the same shape as X such that f?[J] 
is equal to a/I-t-X. For example: 

+ M234 5 6 

1 3 6 10 15 21 

For any associative function a the following definition of R+u\X 
is formally equivalent to the definition f?[I]=a/I+X: 

i?[l]=X[l] 

RlI]=RtI-l]aXlI] for IeliipX 

This definition requires only ~l+pX applications of a (as compared to 
. 5x( P A:)x _ l + pZ) , and is the one actually used for associative functions. 
Because of the finite precision used in machine arithmetic the results 
of the two definitions may differ, and differ signif icahtly , if the 
elements of X differ by many orders of magnitude. For example, compare 
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the last element of the scan with the corresponding reductions in the 
following case: 



DPP*- 5 

X+-1EG 1E6 1E~16 



+ \X 

1E6 1E~16 
+ /X 


+ /<t>x 

1E~1& 



Therefore the scan (as well as reduction) , specifically with respect to 
+ and x, should be used with care in work requiring high precision. 



SYSTEM PARAMETERS AND LIMITATIONS 



SYSTEM VARIABLES 



The horizontal tab , QHT, facilitates both entry and display at a 
terminal with tab stops. The meaningful values of QHT are non-negative 
integer vectors and scalars which denote distances from the left margin. 
The value of QHT in a clear workspace is the empty vector. 
Inappropriate values of QHT result in the report QHT IMPLICIT ERROR when 
QHT is used by the system; that is, at the beginning of any display or 
when a tab is entered on input. 

Effect of QHT on entry: 

While the carriage is within the range of positions indicated by 
QHT, each tab entered is converted to a number of spaces equal to the 
difference between the carriage position and the next larger element of 
QHT. Tabs entered while the carriage is positioned outside the range 
indicated by QHT are not converted to spaces. In particular, when QHT 
is empty, no tab conversion takes place. 

Note that QHT does not control the physical tab stops, nor does 
the system sense the actual tab stop positions set. Therefore, it is 
possible, when QHT does not correspond to the actual tab stop positions, 
to lose visual fidelity. 

Effect of QHT on display: 

Any sequence of spaces is converted to that combination of tabs, 
spaces and backspaces that that will minimize the display time. Spaces 
beyond the range of positions indicated in QHT are not converted. 

Regardless of the value of QHT, the six spaces provided by the 
system to indent before the keyboard unlocks are never tabbed. 

Figure 2 gives, for certain system variables, their value in a 
clear workspace and the range of values that will not result in an 
IMPLICIT ERROR report upon their use. (QAV is listed separately in 
Figure 1 . ) 
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I 



Name 


Value in a clear ws 


Meaningful Values 


UCT 
QIO 
QLX 
DPP 
QPW 
URL 
UHT 


1£~13 

1 
i i 

10 
120 
16807 
lO 


not less than and less than 1 
Oor 1 

character scalar or vector 
integers l through 16 
integers 3 through 3 90 
integers 1 through (2*31)-1 
non-negative integers 



Figure 2. System Variable Values 



NAME LENGTHS 

Names of workspaces, functions, variables and groups are formed of 
| alphabetic (A through Z, A through Z) and numeric (0 through 9) 
'characters, and start with an alphabetic. Only the initial 11 
characters of a workspace name, and the initial 77 characters of other 
names, are significant. Longer names may be entered, but the additional 
characters beyond these limits are not retained, and will be missing 
from subsequent display. The surrogate names of variables shared with 
I TSIO (or of the variables if they are their own surrogates) may not 
exceed 15 characters. 



User account numbers and workspaces are protected from 
unauthorized use by association with a password. Passwords are formed 
from alphabetic and numeric characters and may begin with either an 
alphabetic character or a number. Only the initial 8 characters of a 
password are significant. 

The special rules of naming the OS data sets manipulated by the 
TSIO auxiliary processor are described in the section Data Set 
Identification and Location. 

DOMAINS OF PRIMITIVE FUNCTIONS 

The domains of the arithmetic functions are restricted by the 
constraints imposed by System/370 . 
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For example, the upper limit of the argument to the exponential is 
•L/iO, that is, approximately 174.673, and the upper limit of the 
argument to the factorial function is approximately 56.5452. 

The domains of rank-increasing mixed functions and operators are 
restricted by the requirement that the ranks of their results fall 
within the APLSV range (not more than 64). For example, the sums of the 
ranks of the arguments to an outer or to an inner product operator are 
64 or 65 respectively; the maximum sizes of the left arguments to the 
reshape function and the take function are 63 and 9 respectively; the 
maximum rank of an argument to the lamination function is 24; the 
maximum rank of an array to be indexed is 14. 

The processor identification, which is the argument to QSVQ and 
the left argument to USVO , is a nonnegative integer less than 2*31. The 
delay, argument to DDL, must be less than (2*31)* 30 0. 

WORKSPACE ATTRIBUTES 

The number of names the symbol table can accomodate is at least 
26, and is 256 in a clear workspace. Each name occupies 8 bytes in the 
table. 

The size of a workspace in an APLSV system is the same for all 
users and is determined at the time the system is generated. 

USER ACCOUNT ATTRIBUTES 

Features that vary according to the individual user, such as 
library quota, shared variable quota, and the CPU limit (maximum time 
allotted to a single input line) can be changed, on request, by the 
system operator. 

ADDITIONAL SYSTEM COMMANDS 

Private APLSV libraries have user account numbers greater than 
1000. Libraries with account numbers smaller than 1000 are public. 

In addition to the system commands listed in the APL Language 
publication, APLSV has commands for communication between users or 
between a user and the operator; and for reporting and modifying the 
environment. 

In the text that follows, each system command is shown in a sample 
form. In use, the appropriate names or numbers should be substituted in 
the samples for the following: 

A A letter of the alphabet 

W A number 

USERCODE An abbreviation of user's name 

OBJNAME A name of an object within a workspace 

£ 1 Items enclosed in brackets may be omitted 
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MESSAGE COMMANDS 

)MSG N [ TEXT ] 



Transmits one line of text to the port indicated by n. If N 
does not indicate an active port, the message is reflected to 
the port from which it originated. When the text has been 
dispatched, the system responds SENT. The sending terminal 
accepts no further input, except for incoming messages, until 
either a reply is received or the keyboard is freed. The 
message displayed at port N shows the number of the port from 
which it was sent and the symbol r, meaning "reply expected." 

If no reply is received, the keyboard may be freed for new 
input by signalling a weak interrupt. However, if the user 
signals before the message has been sent, the message is lost, 
and the system reports MESSAGE LOST. 



)MSGN N [ TEXT '] 



Sends a message to port N, but does not inhibit further entry 
while awaiting a reply. 

The message received at port N shows the number of the port 
from which it was sent, but without the symbol R. 



)OPR iTEXT~\ 
)OPRN LTEXT1 



)MSG OFF 



)MSG ON 



Sends a message to the system operator (recording terminal) in 
the same way as )MSG or )MSGN (described above) . These 
commands may also be used from a terminal before the sign-on 
to APL is completed. 



Prevents the delivery of messages, except for a reply to a 
previous )MSG or )OPR command. Following use of )MSG OFF, the 
user's port appears inactive to those attempting to send 
messages to it. That is, messages are reflected back from 
this port to their sources. 



Restores the acceptance of messages suspended during the 
previous )MSG OFF command, and delivers the last broadcast 
message, if any, sent by the system operator. 



) PORTS [#] 



Lists in order the numbers of ports signed on to the same APL 
system as the user [optionally, starting at port N], with the 
first three letters of the account name of each. 



)PORT USERCODE 



Lists the port number (s) of the user whose account name starts 
with USERCODE. 
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ORIGIN, WIDTH and DIGITS 
) ORIGIN N 

Sets the global value of the index origin (QIC) as indicated, 
Valid use of the command results in the message WAS . . . 
showing the former value. An argument other than or 1 
causes the response INCORRECT COMMAND. 



) WIDTH N 



Sets the global value of the printing width LUPWY . Valid use 
of the command results in the message WAS ...» showing the 
former value. An attempt to set a value that is not a 
positive integer, or a value less than 3 or greater than 390 
results in the message INCORRECT COMMAND. 



)DIGITS N 



Sets the global value for the number of significant digits 
appearing in unformatted numeric output (DPP) . This has no 
effect on the precision of internal calculations, nor on the 
display of function definitions. An attempt to set a value 
which is not an integer from 1 through 16 results in the 
message INCORRECT COMMAND. Valid use of the command results 
in the message WAS ..., showing the former value. 



FUNCTION EDITING 



STATEMENT DELETION 



A statement is deleted by following the bracketed statement number 
by attention (or linefeed) and a carrier return, and nothing else: a 
carrier return alone has no effect. 

DUPLICATE LOCAL NAMES 

Duplication of labels and of the names within a function header is 
not checked and will generally produce undesired results. 

PENDENT OR SUSPENDED FUNCTIONS 

A pendent function cannot be edited. An attempt to edit the 
header line of a suspended function, whether it results in an actual 
change or not, produces the error report SI DAMAGE immediately. An 
attempt to edit a label in a suspended function produces the SI DAMAGE 
report when function editing mode is ended. An SI DAMAGE report is 
issued only once for each editing session of the function. 
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PRINCIPLES OF OPERATION 



The TSIO auxiliary processor makes available to the APLSV user, 
through the use of shared variables, many of the data management 
facilities of the OS/VS operating system. This section describes how to 
make effective use of these facilities for operations such as the 
construction and use of files outside of an APL workspace, and certain 
types of high speed input and output. 

In the host system, all operations involving input and output or 
auxiliary storage are said to concern data sets . Initially names are 
assigned to collections of data that are to be created on a storage 
device. The resulting data set can be accessed at a later time by 
referring to its assigned name. A data set is said to be opened when 
the necessary preparation for accessing it is complete. This usually 
involves the deployment of programs and storage facilities for managing 
data transfer between the storage device and the computer memory. When 
transfer operations are finished, the facilities are made available for 
other uses and the data set is then said to be closed . 

Data sets are composed of records grouped in blocks , which are the 
units of information actually transferred between the storage device and 
the computer memory. A block may consist of only one record or of many. 
When a data set is constructed exclusively with blocks containing only a 
single record, the data set is said to be unblocked . 

The information required by the system to open a data set varies, 
depending chiefly on whether the data set is new or old, the complexity 
of its format, and the acceptability of certain default options provided 
by the system. In the APL environment, this information is provided by 
the user in the form of a character vector, which TSIO translates into a 
form understandable by the operating system. Responses by the operating 
system are accepted by TSIO, which sends them on to APL. A single 
shared variable, called a control variable , is used for this two-way 
communication. 

Once the data set has been opened, data transfer can start, using 
either the control variable or, in certain cases, an associated shared 
data variable . Data transmission is mediated by TSIO, which may remove 
or supply the header - the descriptive information that is part of the 
internal representation of all APL data. TSIO also monitors the control 
variable for the appearance of an empty vector, which is used to signal 
the end of data transmission and the closing of the data set. A 
retraction of the control variable for any reason will also end the 
operation in progress and force the data set to be closed. 

COMMUNICATION WITH TSIO 

Communication with the TSIO processor is established through a 
shared variable whose (surrogate) name must begin with the characters 
CTL. This variable is called the control variable . In indexed reading 
and writing, a second shared variable is required and its surrogate name 
must begin with DAT and conclude with the same suffix used in the 
control variable name. This variable is referred to as the data 
variable . Several different pairs of data and control variables may be 
shared with TSIO, the pairing indicated by the name suffixes as in CTLB 
and DATB , or CTL5 and DAT5. Each pair is treated independently by TSIO. 

The identification number assigned to the TSIO processor may 
differ with each installation. However, as with all auxiliary 
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processors it must be identified by a positive number. Using the 
variable T to indicate this assigned value, the control variable can be 
shared as follows: 

T QSVO 'CTL< 

1 

From here on the term i nterlock will be used for the access 
control imposed on a shared variable. Even though TSIO places a full 
interlock 1 1 1 1 on CTL as soon as it accepts the offer, this 
acceptance may not be immediate. It is desirable that this acceptance 
and interlock be established by the APL user before further action is 
taken. This can be insured as follows: 

1111 DSVC 'CTL' 

1111 

Except for the explicit synchronization provided by a full 
interlock on the control variable, the operations of TSIO and the data 
management system are independent of, and not synchronized with, the 
execution of any APL program which communicates with it. 

CONTROL VARIABLE MODES 

Since a control variable may be used for data transfer as well as 
for the initiation of operations, a protocol is defined which allows 
TSIO to determine which type of information is being communicated. The 
value of the control variable will be interpreted by TSIO to be a 
command only when the control variable is in command mode , which occurs: 

o Immediately after the user's offer to share the control variable has 
been matched by TSIO. 

o Immediately after the execution of commands which request a one-step 
operation, such as renaming or deleting a data set. 

o After the termination of data access, as indicated by the user or by 
TSIO while in data transfer mode . 

The value of the control variable will be interpreted by TSIO to 
be data to be transferred only when the control variable is in a data 
transfer mode . Data transfer mode is established by the successful 
execution of a command which requests data set access. Data transfer is 
ended as follows : 

o Termination of data access is signalled by assigning an empty vector 
to the control variable, or by explicit or implicit retraiction of that 
vairiable. 

o TSIO will normally terminate data transfer only in a sequential 

reading operation. In this case, the next use of the control variable 
after the last successive record has been read yields an empty vector; 
the following use yields the numeric return code resulting from the 
end of the read operation; and the control variable is in command 
mode. 

o TSIO will also terminate data transfer during a sequential write 

operation if certain errors are encountered. In this case the control 
variable yields a numeric return code immediately, and the control 
variable is in command mode. When the data set is closed, TSIO 
retracts the control variable . 
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DATA MANAGEMENT COMMANDS 



A command is a character vector that begins with a word (or 
abbreviation) designating the operation to be performed, followed by a 
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space and a sequence of one or more items separated by commas. The 
items in a command can appear in any order. They are used to establish 
the parameters which govern the attributes or the usage of the data set. 

sion foliS£fl S hv C » S ™'i™ ± H? £ ons±s £ s °f a keyword followed by an equal 
sign tollowed by a value, which may be a name, number or another 
keyword. The commas and the equals sign may have any number of spaces 
on either side. For example: F 

CTL+'ShT DSN = A1, DISP=NEW, BLKSIZE = 550' 

an , °" e ^ em mu ?t a lways identify the data set (for example, DSN=A1) , 
and other items either describe physical attributes of the data set (for 
example, BLKSIZE= 55 ) , or further describe the function to be performed 
on it (for example, DISP=NEW) . 

Q »»h / h ?2 * Parameter value has'multiple fields, the significance of 
each field is determined by its position. A convention involving both 
commas and parentheses is used for representing the several values 
Since only four parameters are affected by these conventions, the 
details are given for each as its use is explained in the text. 

Eleven data management operations are provided by TSIO, of which 
four (CATALOG, UNCATALOG, READVTOC , MSG) , are restricted to those users 
identified to TSIO as system level users, to be described in a later 
section. The seven data management operations available to all users of 
TSIO are shown in Figure 3. 



ABB REV. 



SW 

SR 
IRW 

IR 

RENAME 
DELETE 
IC 



I 



OPERATION 



Sequential Write 

Sequential Read 
Indexed Read and Write 

Indexed Read 



Indirect Command 



MEANING AND USAGE 



Create a new data set, and rewrite 
or append to an existing 
data set. 

Read records sequentially from 
an existing data set. 

Read and write records in 

arbitrary sequence from 

or to an existing data set. 

Read records in arbitrary 
sequence from an existing 
data set. 

Change the name of an existing data set. 

Delete an existing data set. 

Execute a prepared command from a 
command data set. 



Figure 3. Data Management Operations 

RESPONSE CODES 

The assignment of a command to the control variable in command 
mode results m either the successful performance of the indicated 
operation or in failure. in either case, the value of the control 
variable is a response code which indicates either that the command has 
been successfully executed or the reason for failure. A zero indicates 
success; the significance of other codes is given in Figure 4. Response 
codes are also used during data transfer as shown in Figure 5. 
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CODE 





1* 

2* 



3 
M- 

5 

6 

7 

8 

9 

10 

11 

12 

13 



NAME 



Normal 

Imparsible 
command 

Restricted 
command 



R 1^ 

E 

S 15 

O 

U 16 

R 

C 17 

E 

S 18 

19 

20 



DSNAME error 

BLKSIZE error 

LRECL error 

DISP error 

RECFM error 

UNIT error 

70£= required 

NEWNAME error 

Duplicate 
name 
Dataset not 

found 
Member not 

found 



RESPONSE 
TO 



Anything 
Anything 
Anything 



I/O buffers 

full 
Data set in 

use 
Volume full 

PDS directory 
full 

Volume 
unavailable 

Already 
cataloged 

Control vari- 
able in use 



Command 
S I 

s 

SR I 
I 

Command 
Command 

REN 

DISP=NEW 

Command 

S D REN 



CAUSE, RESULT, AND CORRECTIVE ACTION 



S I 

Command 

SW 

sw 

Command 

SW REN 
Command 



Success 

Parse of command failed. 

Operation, parameter, or parameter value 
requires different level authorization. 
DSN missing or bad name. 



BLKSIZE missing or too large. 

FB, VB need LRECL ; or LRECL>BLKSIZE. 

DISP----NEW 

RECFM*F (In IRW , RECFM is determined by 

the data set.) 
CATALOG needs UNIT, or data set not 

cataloged, or no such UNIT. 
The combination DSN, UNIT, and DISP*NEW 

needs VOLUME. 
NEWNAME missing or *DSN for PDS. 

DISP -NEW and name already used. 

DISP*NEW and name not found. 

Member of a PDS not found. 



Available space in TSIO region smaller 

than buffer. See Note 1. 
Data set in use with DISP*SHR. 

Insufficient space for primary 

allocation. 
Attempting to write a new member when 

directory of a PDS is full. 
DASD volume not mounted or request to 

allocate unit record device denied. 
(With DISP=NEW) Name already cataloged or 

name conflict as in A.B.C and A.B 
Last used with DISP of LEAVE or REREAD. 

Use new variable or retract and reshare. 



LEGEND AND NOTES 



D DELETE 

I IR or IRW 

S SR or SW 

REN RENAME 



PDS Partitioned 
Data Set 
DASD Direct Access 
Storage 



* These codes have a 
second element that 
shows the point of 
difficulty in the 
command . 



1. Try later or 
ask operator 
to allocate 
more space. 



Figure 4 : Response in Command Mode 



12 APLSV USER'S MANUAL 



CODE 



NAME 



DURING 



CAUSE 

ACTION (None unless stated) 





21 

22 

23 
24 
25 
26 
27 

28 
29 



30 



Normal 

Data type 
error 

Data length 
error 



Data rank 
error 

File index 
error 

CTL domain 
error 

DAT variable 
required 

Variable too 
large for 
SVS 

I/O error 



Data set 
full 



System error 



S I 
S I 

S I 



I 



S I 



s w 



S I 



Success. 

Data type not appropriate to CODE. 

SR: Data set closed; to command mode. 

RECFM=F,FB and RL* (for C0DE*A) or <(for 
CODE-A) BLKSIZE or LRECL, respectively, or 
RL>BLKSIZE. 

SRt Data set closed; to command mode. 

CODE* A and data not a vector. 



Index > number of records in data set. 



CTL not a 2-element non-negative integer 
vector with leading 1 2 3 4 or 5 . 

DAT variable (with suffix = CTL suffix) not 
shared on first data transfer attempt. 

Shared variable storage area too small. 
SR: Data set closed; to command mode. 
CODE*- A. 

Physical error in data transfer. 

SR , SW: Data set closed; to command mode 
IRW (writing) : Record may have been 
destroyed. 

16 extents have been allocated and filled, or 
no space on volume for a needed secondary 
allocation, or primary allocation filled" and 
no secondary allocation specified. 

Data set closed; to command mode. 

See legend for *. 

All relevant terminal output should be 
given to the system manager. 



CTL Control 

Variable 
DAT Data Variable 
RL Record length 
S SR or SW 
I IR or IRW 
R Reading 
W Writing 



* Second element of response code (for code 30) 
has the following significance: 



VTOC full 

Allocation failed 5. 
DD card missing 6. 
System queue error7 . 



L- 



System queue full 
Directory error 
CATALOG failed 
8. OPEN failed 

(Also see APLSV Operations Guide, 

IBM Publication SH20-1461.) 



Figure 5 : Response in Data Transfer Mode 



SEQUENTIAL READING AND WRITING 

Data sets can be created and extended by sequential writing only 
They may be accessed sequentially by the commands SW and SR (see Figure 
7). The following example shows the creation, reading, extension, and 
rewriting of a data set: 



T USVO 'CTL' 



Share control variable with processor 
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llll QSVC 'CM' Impose access control on (i.e. interlock) the 
l 1 1 1 shared variable 

CTL-*- ' SW DSN = A1 , BLKSIZE= 5 5 0, DISP=NEW ' 

issue command to create data set 

The value associated with DSN is the name of the data set. The 
BLKSIZE parameter value specifies the largest size of a block within the 
data set. The value of VI SP indicates that the data set is to be 
created. This is the minimum information required for the creation of a 
data set. 

A zero response indicates that the command 

has been successfully completed. 

Data transfer can now take place: 



CTL<-\8 
CTL 



Value for first record is transferred. 



o 



Response indicates record has been 
successfully written. 
CTL+-2 3p<ABCDEF x Value for second record is transferred. 

CTL Display of response. 

CTL+-* ' Empty vector requests return to command mode. 

CTL . . ,_ . ^ , 

Response indicates that wrxting terminated 

normally and the data set is closed. 

The display of responses from TSIO can be omitted without altering 
the essential behavior of TSIO; output data transfer is initiated as 
soon as CTL is set, and input as soon as it is used. However, it is_ 
good practice to read and check each response, so that error indications 
can be used to identify trouble, and meaningful continuation will be 
assured. 

The records in the data set Al created in the previous example can 
now be read sequentially as follows: 

CTL+'SR DSN=A1 % Open Al for sequential reading. 

CTL Response to command. 



First record is read and displayed. 





CTL 
12345678 

X<-CTL Second record is read. 



X 



ABC 
DEF 



Ctl Response from TSIO is an empty vector, 

indicating that it has been returned to 
command mode by the reading of the final 
item in the data set. 



CTL 



Response indicates that the reading 

terminated normally and the data set is 
closed. 
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Further records can now be appended to the end of the data set, as 
follows: 

CTL*'SW DSN=Al,DISP=MOD t Open AX in such a way that access 
starts after the last record. 

CTL*\Z Append a record 

CTL 


CTL*' ' Request return to command mode 

CTL 


At this point Al has three records, each containing an APL value. 
To rewrite the data set from its beginning, the SW command is used 
omitting the DISP parameter: 

CTL*'SW DSN=A1< DISP default value is OLD 

CTL 


The above command erases the records in Al , while still retaining the 
identity of Al as a data set. The next data item transferred will 
become the first record in Al . For example: 

CTL*- 1 A FRESH START' 

CTL 


CTL* ' ' 

CTL 


The data set Al now contains one record only. 
INDEXED READING AND WRITING 

Data sets can be created and extended by sequential writing only, 
but records of existing data sets can also be accessed non-sequentially, 
by means of the commands IR and IRW . Indexed access makes use of two 
variables shared with TSIO: the control variable, whose (surrogate) name 
must begin with CTL, and a data variable, whose (surrogate) name must 
begin with DAT . 

This method of access can be used only for data sets containing 
uniform length, unblocked records, which are produced by an SW command 
in which the RECFM parameter is F (fixed and unblocked) (but note that 
the workspace 1 APLFILE , described later, permits indexed access of APL 
variables of arbitrary rank and shape ) . 

The following example shows the sequential creation of a data set 
and its indexed use: 

T DSVO * CTL ' Share control variable with processor T 

1 

1111 QSVC 'CTL 1 Impose access control on the shared variable 

llll 

CTL* ' ' Enter command mode 

CTL* > SW DSN=A 2 , BLKSIZE= 5 5 0, DISP=NEW , RECFM=F • 

Create RECFM=F data set 
CTL Test for successful opening. 

CTL*loo write first record 

C 1 Li 



SECTION 3: USE OF TSIO 15 



CTL+-200 Write second record 

CTL 


CTL+ZOO Write third record 

CTL 


CTL-*-'' Terminate writing. 

CTL 


T USVO 'DAT 1 A data variable must be shared sometime 

before indexed access actually begins. 
1 

CTL+'IRW DSN=A2 f The data set is opened for indexed access. 

CTL 


Once the data set has been opened, reading or writing is signalled 
by assigning a two-element control vector to CTL. The first element of 
this control vector is the operation code , which may have a value, of 0, 
1, 2, 3, 4, or 5. When the operation code is or 1, signifying a read 
or write , the second element of the control vector specifies the index 
of the record to be accessed — always in 0-origin. 

The use of the operation codes for read and write is illustrated 
in the example here; the significance of control vectors using other 
operation codes is discussed later, in the section on Shared Data Sets. 

During indexed access all synchronization is managed by the 
interlock on CTL. When reading, CTL must be referenced after being set, 
to ensure that DAT has the proper value. When writing, CTL must be 
referenced before the new value is placed in DAT, in order to be sure 
that the last operation has been completed; and only after DAT has been 
specified should CTL be set. 

CTL+Q 2 Read record number 2. 

CTL 
Response indicates that the operation is 

completed, and DAT has the proper value. 



DAT 



300 



To assign the value ' X' to record number 2 of A2: 



DAT+'X } 
CTL+1 2 
CTL 


It should be noted that a continuation such as : 

CTL+1 1 
CTL 


would assign the same value 'X' to record number 1 as well, since DAT 
remains shared (and not interlocked) and TSIO uses the current value 
whenever CTL indicates a record is to be written. 

To open the data set for indexed access for reading only, for 
example to protect it against accidental revision or to allow several 
users to read it concomitantly, the sequence might be: 

CTL-*-' ' 
CTL 
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CTL+- X IR DSN=A2< 




CTL 









CTL+-0 2 




CTL 









DAT 


300 




and 


so on. 



Access by IRW and with parameters BLKSIZE , RECFM or LRECL 
different from the ones with which the data set has been created will 
alter the values of these parameters, whereas access by IR will not. 
Further, if a data set created for use with indexed read and write is to 
be extended by a sequential write operation with DISP=M0D, the 
parameters BLKSIZE, LRECL, and RECFM should be omitted, so that those 
already in existence will remain in effect. 



USER LEVELS 

Any APLSV user having a non-zero shared-variable quota can offer 
to share variables with TSIO if the user knows its identification 
number, but TSIO will accept offers only from users whose account 
numbers are known to it. Each user thus authorized to use the processor 
is permitted usage qualified further by a combination of the four 
discriminants detailed in Figure 6 below. The set of discriminants 
associated with a given user is referred to as the user's level . 



DISCRIMINANT 



DEVICE 



ACCESS 



SYSTEM 



USER QUALIFICATION 



Allowed to create new direct access data sets, which 
implies the allocation of storage space. 

Allowed to use the UNIT and VOLUME parameters, which 
implies the allocation of specific devices or storage 
units. 

Allowed indexed access or sequential reading of other 
TSIO users' non-reserved data sets, given a knowledge 
of their identification. 

Has use of commands beyond the seven available to all 
users, and access to any data set, including those vital 
to system operation, within the constraints of the 
operating system security provisions. 



Figure 6. User Levels 

| These qualifications are used to control the use of system 
resources, assur'e the integrity of the system, and serve the interests 
of privacy. 

DATA SET ORGANIZATION 

TSIO directly supports OS/VS data sets organized in three ways: 

Sequential in which records can be accessed only in the sequence of 
their (linear) physical relationship. This organization is available on 
all storage devices, and is mandatory for tapes and unit record devices. 

I Direct in which records may be accessed in arbitrary sequence (once they 
have been sequentially established) . Available only on direct-access 
devices. 

Partitioned in which independently accessible groups of sequentially 
organized records are identified by compound names with a common first 
part. Available only on direct-access devices. 
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DATA SET PRIVACY 



Provision for enhanced security of data sets created under TSIO is 
embodied in the use of reserved data sets with controlled access. A 
data set is said to be reserved to a user when the name of the data set 
is qualified by the negative of the user's account number. This user 
can access the data set freely, but other users can access it on a 
restricted basis only, as follows! 

1 . A data set reserved to a particular user can be accessed by other 
users directly, but only for the purpose of obtaining access to 
another data set reserved to that user. It is convenient to 
refer to a reserved data set used in this way as a c ommand data 
set . 

2. A data set reserved to a particular user can be accessed by other 
users for reading and writing only indirectly, through the 
mediation of a command data set reserved to that user. 

However, batch jobs, which always execute at the system level of 
privilege, can access any TSIO data set. 

Consider the case in which user 1234 wishes to authorize user 5678 
for indexed reading of the reserved data set "12 3"+ SECRETS. To 
accomplish this, user 1234 stores an image of the command IR DSN~~123H 
SECRETS as, say, the eleventh member of the reserved data set "1234 
GATEKEEP. Subsequently, after shciring a control variable with TSIO in 
the normal way, user 5678 may submit a request for an indirect 
operation, using an IC command: 

CTL+'IC Z?£W=~12 34 GATEKEEP (11)' 

On receipt of this command, TSIO will first determine that ""1234 
GATEKEEP has the proper format for a command data set, then check the 
authorization matrices within it to determine whether user 5678 is 
permitted to utilize command form 1 1 . Only if both of these checks are 
satisfactory will TSIO execute the read command on behalf of user 5678, 
who may then proceed with normal reading of "123 4 SECRETS. 

If the data set "1234 GATEKEEP does not exist, or if it is not 
properly constructed as a command data set, or if user 5678 has not been 
authorized to use the eleventh command, then TSIO issues the return code 
2 1 to user 5678. 

A command data set must have C0DE=A, RECFM=F, BLKSIZE=320. 

Record of the command data set must be an integer vector with 
the following elements: 

[0] First authorization matrix record number (typically 97) 

Cl] Last authorization matrix record number 

[2] Maximum number of rows in authorization matrices (maximum 19) 

[3] Last block allocated for authorization matrices 

[4] Number of authorized user entries, total for all 

authorization matrices 
[5] Creator's user identification 
[6 7 8 9 10 11] Year, month, day of month, hour, minute, second 

of last update of the data set 

Records 1 to 96 of the data set provide for the indirect commands. 
From record 97 on the records are authorization matrices of 128 columns 
and of a number of rows no greater than element [2] of record 0. 
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Columns to 31 of these matrices contain the (32 bit) 
twos-complement representations of user identification numbers. Columns 
32 to 127 correspond to records 1 to 96 of the data set: if the element 
in row I, column 31+/ is 1, the command in record J may be executed on 
behalf of the user identified in columns to 31 of row J. 

An entry for user represents a general authorization for users 
other than those listed in the authorization matrices . A 1 in column 
31+^ of this row permits such users to execute the c/-th command. 

Each authorization matrix except the last must have the maximum 
number of rows as given by the element [2] of record 0. The rows of all 
the authorization matrices, considered as one matrix, must be in order 
by the base-two values of columns to 31. 

Command data sets are created and maintained by means of APL 
functions distributed in the workspace 1 TSIO. The necessary 
instructions for their use are found under ICDESCRIBE in that workspace. 

SHARED DATA SETS 

There are many applications in which the same data set must be 
used asynchronously by a number of different users. To a certain extent 
this can be managed without conflict by appropriate use of the 
disposition parameter, but this alone may not be completely 
satisfactory. On the one hand, if the data set is opened for exclusive 
use by one user, no matter how small the portion of the records actually 
involved, no other user can access any part of it until the data set has 
been closed and reopened. On the other hand, if the data set has been 
opened for shared use, except for the simplest case, in which all the 
sharers are only reading, some further mechanism is necessary to provide 
more dynamic control and finer resolution of the shared use. 

Such a mechanism is provided by the operation codes 2 3 4 and 5, 
which may be used in the control vector {CTL) when a data set has been 
opened for indexed access with DISP=SHR. When one of these operation 
codes is used, the second element of the control vector may have any 
non-negative integer value. Except for zero, the significance of this 
value is completely arbitrary, although commonly it may be a record 
number or a coded identification of a set of records. 

The operation codes 2 and 3 signify that the user wishes to have 
exclusive use of the facility denoted by the second element of the 
control vector, either immediately (2) or whenever it becomes available 
(3) . The operation codes 4 and 5 signify that the user wishes to have 
non-exclusive use of the facility, — on a shared basis, simultaneously 
with other users — either immediately (4) or whenever it becomes 
available for such use (5). In any case, once use of a facility has 
been acquired, the user is said to have an exclusive hold or a shared 
hold on that facility. 

If more than one control variable has been attached to a data set, 
each one may independently have a hold on a facility associated with 
that data set. An existing hold associated with a control variable is 
automatically cancelled by any subsequent use of one of the operation 
codes 2 3 4 5, whether or not the new request is fulfilled. An existing 
hold can also be cancelled explicitly by using a zero for the second 
element of the control vector with any of these operation codes. 

Consider for example the following function, several instances of 
which are assumed contending to update records 100-120 of DATASET: 
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V F;I 
[1] TCTL 'IRW DSN=DATASET' 
[2] TOCTL 3 7 
[3] J«-0 

[4] Ll:-»-(120<99+I-<-I+l)/L2 
[5] DAT+-RECORD I 
[6] TOCTL 1,1 
[7] +L1 
[8] L2 -.TOCTL 3 

V 

v itoctl *;£ 
C i ] ctl^a: 

[2] +(0=E+CTL)/0 

[3] 'TSIO RESPONSE: « ,▼£ 

[4] o 
V 

The updating is performed by the function RECORD. The contender 
that achieves exclusive hold on facility 7 of DATASET will next update 
records 100-120. 

If a request for an immediate hold on a facility cannot be 
fulfilled because the facility is being held by another user, the 
control variable is returned with the value 15. Note that a request for 
exclusive use may be denied either because another user has an exclusive 
hold or a shared hold, and that a request for a shared hold may be 
denied only if another user has an existing exclusive hold. A request 
for a hold with codes 3 or 5 , indicating that the user can wait, will 
remain in force until the facility becomes available for the type of 
hold requested, unless cancelled by retracting the variable. The 
fulfillment of the request is sgnified by the value in the control 
variable, which is, as usual, interlocked against reading until TSIO 
respecifies its value following receipt of the request. 

Two points are worth noting : First, the use of these operation 
codes does not automatically guarantee protection against conflicting 
use or other problems associated with shared facilities. It merely 
provides the potential for such protection to be incorporated in an 
application program. Thus, for example, there is no built-in constraint 
against the use of the and 1 operation codes for reading or writing 
into a record which is otherwise part of a facility held by another 
user. 

Second, because of the absence of such built-in constraints, the 
definition of the facilities denoted by the second element of the 
control vector when using an operation code of 2 3 4 or 5 is completely 
up to the application program, and need not refer in any way to the data 
set in use. In such a case the data set acts as a communication device 
with certain useful properties. The application will be making use of 
the built-in queuing facilities of TSIO, as well as the properties of 
the operation codes, to control the use of some common resource. 

TSIO COMMAND PARAMETERS 

Figure 7 shows parameter usage for each of the generally 
available operations, for parameters of general interest. Usage of 
parameters applicable only to tapes, or whose use is restricted, is 
given in appropriate sections. Where the table entry is C (for 
caution) , the use of the parameter is not required, may sometimes be 
useful for a special purpose, but could result in damage to the data set 
or its label. In case of doubt, the publications mentioned in the 
preface should be consulted. 
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NOTES 


USE 


DEFAULT 


1 . See Figure 5. 


C With caution 


L From label Parameter 




E Error 


or record values (in 


2. Parameter value may be 
compound . 


Optional 


APL font) 


R Required — 




Q Required for C0DE*A 


3. BLKSIZE is required for data 


Blank-Ignored 


sets that do not have 




standard labels. 
4. (1000,(100,0)) for 




OPERATIONS 


sequential data set 


SW Write sequentially 




SR Read sequentially 


(1000,(100,0,5)) for 


IR Read with index 


partitioned, data set 


IRW Read and write with index 




RENAME Change the data set name 




DELETE Expunge the data set 




IC Command indirectly 





(See text for DEN, EXPDT , LABEL, TRTCH, UNIT, and VOLUME) 
Figure 7. Data Set Operations, Parameter Usage, and Default Values 



Figure 8 summarizes the command parameters in the style of the 
OS/VS JCL Reference Manual, so that the reader may compare TSIO keywords 
to JCL keywords. 
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PARAMETER USAGE 



LBLKSIZE- block size] 



C } 



[ CODE- { C 
E 

F 
I 

0\ 
1 
LDEN = { 2 
3 

4 



(NEW) 
OLD I [ ,1 LEAVE I ])] 
MOD | [REREAD! 
SRR> 

iDSN J 

1 }=[[-]user no. ]dsname[ (member) ] 

( DSNAME) 

[£TPz>y=yyddd] 

tKEYLEN=k&ylength-l 



IBLP 
C LABEL= (data set seq no.[,jii/£ } ])] 

[SL 

LLRECL=record size] 



LNEWNAME^Ll-lusex no. ]dsname[ (member ) ] 



IRECFM- 



ISPACE= (blocklength, (primary[ , sec- 
ondary[ .directory] ] ) ) ] 



LTRTCH=)E I] 

I device type j 
group name }] 
unit address! 



(U 1 




F 




V 


LA 1 


FB 


M 


VB 




FBS 





[ I VOL 



I VOL I : 

[VOLUME] 



■■[SEE volume serial 



[SISOUT= (output class [ , [pgm name ] 
[ ,form number ] ]) 



COMMENTS 



Required with DISP=NEW or 
LABEL^NL or BLP 



Required when accessing 
non-APL data sets 



Used only with UNIT=tape 
and DISP=NEW 



See Figure 7 for defaults 



Required except 

for REAVVTOC or SYSOUT 



Only with SW DISP=NEW 

Only with DISP=OLD or SHE 
and UN IT= direct access 



Only with UNIT=tape 

With RECFM=FB and DISP=NEW 
or LABEL=BLP or tf£ 

With RENAME command 



Only with DISP=NEW or 
LABEL=BLP or tf£ 



Seven track tape only 
Normally not required 



Use prevents cataloging a 
non-TSIO data set 

Consult local 
System Administrator 



Figure 8. TSIO Command Parameters. 
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DATA SET IDENTIFICATION AND LOCATION (DSN, UNIT, VOLUME) 

When a data set is created on a direct access device, information 
about it is automatically stored in a label on the same volum e of 
storage - that is, on the disk pack or drum - that contains it. Label 
data includes control information such as space allocation and data set 
format .. For some formats (F, FB) , all the control information is in the 
label; for others it is partly distributed throughout the data set, 
either explicitly {v, VB) or implicitly (y) . 

TSIO provides, for each new data set, an entry in the system 
catalog , a data set which lists the names and locations of data sets 
available in its particular installation. Locations are designated by 
volume serial number and unit , a reference to the type of device on 
which the volume containing the data set may be mounted. 

Data Set Names 

New data set names are composed of one or more simple names joined 
by periods, as in DEPT 58 .SMITH .DAT A3. Each simple name must begin with 
an alphabetic or national character (see Figure 9) , and may continue 
with at most seven more characters which may also include numerals. 
Compound names are treated by the system as a succession of qualifiers 
or indices in a tree-like structure leading from the major index, or 
root, on the left, to the name itself, or leaf, on the right. _ The 
maximum length of a (qualified) name is 44 characters, including 
periods. 

Except for system level users, TSIO prefixes the name supplied in 
the DSN parameter with a two-level qualifier composed of the name TSIO 
and a character representation of the (positive or negative) account 
number U supplied: 

'TSIO. ' , iABCDEFGHIJKLMNOP'[.niO + (8pl6)TU~] , ' . ' 

For example, if the name above used account number 12 34, the fully 
qualified name transmitted to the system by TSIO would be 
TSIO .AAAAAENC .DEPTS8 .SMITH .DATA3 , while if it used the negative account 
number "12 3 4 the fully qualified name would become 

TSIO .PPPPPLCO .DEPT58 .SMITH .DAT A3. 

In the case that an account number is not provided, the system 
supplies the (positive) account number of the user. For an alien data 
set or for a reserved data set the qualifier must be supplied explicitly. 
Thus, for user 5 67 8 to access the data set in the example, he would have 
to use the form, DSN=123H- DEPT58 .SMITH .DATA3. (User 1234 could use 
exactly the same form, but need not because his account number is 
supplied by default, much as for APL system commands. The first 
qualifier, TSIO., is never supplied explicitly.) 

A data set name may be further qualified in a different sense by 
appending to it another name enclosed in parentheses, as in 
DSN=ABC{PART±). A set of such names (such as ABC(.PAHT1 ) and ABC(PART2 )) 
constitute a partitioned data set. Casual use of such data sets is not 
recommended; the interested user should consult the OS/VS references or 
a knowledgeable programmer before planning their use. 

Data Set Locations 

Unless otherwise specified, TSIO will allocate space for new data 
sets on a volume of a direct access device, selecting the particular 
volume from a more general allocation made previously by the system 
managers. Creation of a data set on other volumes, or access to 
non-cataloged data sets, requires explicit use of the UNIT and VOLUME 
parameters in the command. 
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Since specific device allocation (for old as well as new data 
sets) implies the arbitrary disposition of system resources in terms of 
both storage space and active use of devices, use of the UNIT and VOLUME 
parameters is restricted to users at the device level. Moreover, for 
all tape volumes, and certain direct access volumes, active cooperation 
of the system operator is required, and the operator should be consulted 
before these parameters are used. 

If the UNIT parameter must be used - for example, to input data 
from a card reader - its value is chosen, according to the 
circumstances, to be either a specific device unit address, the 
designation of a device type (such as 3330) , or an 

installation-dependent class name that denotes a collection of devices 
of possibly divergent types. The VOLUME parameter is always given as a 
serial number that identifies a disk pack or tape reel. 

DISPOSITION (DISP) 

The disposition parameter, DISP, is used primarily to position the 
device with respect to the data set. Secondarily, it determines whether 
or not a data set can be shared during an operation, and also, through a 
second field in its value, allows the data set to remain allocated with 
the device in position after the data set is closed. The latter 
facility is of most interest in tape operations. 

The values for the first field of DISP are NEW, OLD, MOD, and SHR. 
The first three are explicitly positional, calling respectively for the 
device to be positioned, when opened, at the beginning, beginning, or 
end of the data set for a sequential operation, but imply exclusive 
control by one user. The fourth value explicitly allows more than one 
user concomitant access, but implies that the operation is to start at 
the beginning of the data set. 

The second field may have the value LEAVE or REREAD, which 
positions the device at the end or beginning of the data set when it is 
closed. In either case the data set remains allocated to the user who 
opened it, until that user either reopens it for further activity with a 
different disposition or retracts the control variable. When used with 
a tape, this parameter permits the user to read the same data set 
several times {REREAD) , or to read successive data sets on the same tape 
volume (LEAVE) , without intervention by the system operator. 

A complete specification of the DISP parameter has the form 
DISP=(M0D, LEAVE), if the second field is not used, the simple form 
DISP^MOD suffices. 

DATA REPRESENTATION (CODE) 

In transferring data between an APL workspace and the operating 
system, TSIO transforms the internal representation of APL values 
according to the value of the CODE parameter. In the default case, 
C0DE=A, the transformation is minor: TSIO merely replaces the first 
eight bytes of the header (which are used for internal addressing) by 
four bytes giving the length of the representation. For the other code 
values the transformation involves the total removal or replacement of 
the header. The values of the CODE parameter are: 

A APL representation I integer 
B boolean F floating-point 

C character E character with APL-EBCDIC 

translation 
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When the same code value is used for both writing and reading a 
data set the transformations are not perceptible to the APL user, except 
that code a requires slightly larger records. If different codes are 
used for reading and writing, a variety of effects can be achieved. 

A variable x written with CODE=A requires four bytes less space 
than the amount it takes up within the workspace (see formula under the 
heading Arrays) , rounded to the nearest word (four bytes) . A variable 
stored with C0DE=A and retrieved with some other code will start with an 
approximate representation of its original header. It may also end with 
meaningless fill, especially when RECFM=F is used with code a, since 
TSIO then provides fill to complete the specified record size. 

When written with any code but A, the array to be passed from APL 
to TSIO must meet shape and size requirements imposed by the RECFM , 
BLKSIZE, and LRECL parameters. These are detailed in the section DATA 
SET FORMATS below. 

When reading with any code but A, TSIO provides the indicated 
personality by appending an appropriate header during the transfer. If 
the number of bytes in the record is not an integral multiple of the 
unit of internal representation, the record is truncated. When reading 
with code At the first part of the record is interpreted as a header 
and, if invalid, may prevent reading of the record, so that the data 
transfer variable has no value. 

Writing a data set with COVE - E causes a translation from APL 
characters to EBCDIC characters, and reading causes a translation in the 
reverse direction. These translations are specified in Figure 9. 



APL 
EBCDIC 


ABCDEFGHIJKLMNOPQRSTUVWXYZ 
ABCDEFGHIJKLMNOPQRSTUVWXY Z 


APL 
EBCDIC 


ABCDEFGHIJKLMNOPQRSTUVWXZZ 
abcdefghij klmnopqrstuvwxyz 


APL 
EBCDIC 


0i23t56789 space 
0123456789 space 


APL 
EBCDIC 


-~***',.;:()/*<>*aA = A? + _| <J> e 
--*"', .; : ( )/%<>$@#=&?+_|+0-0 


Notes: 




1. All other APL characters map into EBCDIC space, except APL *• and 
which map, respectively, into EBCDIC = and -. 

2. All other EBCDIC characters map into APL o. 

3. The characters $ a # are referred to as national characters and may 
be represented by different graphics in different countries. 

4. The +o and -o are obtained by overpunching. These values occur in the 
zoned decimal numeric representation used in keypunch data. j 



Figure 9. APL-EBCDIC and EBCDIC-APL Translation 

DATA SET FORMATS {RECFM, BLKSIZE, LRECL) 

The OS/VS record formats supported by TSIO are given in Figure 10, 
which describes their structure and the requirements imposed on the 
block size and record length parameters in the use of each. 
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RECFM 



Description, transmission form when CODE is not A 



FB 



FBS 



VB 



Fixed length blocks, containing only one record, transmitted 
as a vector. Only format available for creating datasets for 
use with ir and IRW. 

Variable length blocks, of length up to BLKSIZE, each 
containing some number of fixed length records; each record 
transmitted as a vector. 

Fixed length blocks, each containing a fixed number of 
records; each block transmitted as a matrix of size M N where 
M is BLKSIZE * LRECL and N is given below. May not be used 
with code A. 



N is LRECL i 
when CODE is 



.125 1 
B C 



1 
E 



4 

I 



Final record may be of size 
is from dataset close. 



L N where L < M; next return code 



Variable length self describing blocks, containing variable 
length self describing records, which are transmitted as a 
sequence of vectors whose length, when writing, must be less 
than LRECL- 4, to accomodate the descriptors. BLKSIZE must 
be at least LRECL + 4. 

Exactly the same as VB except that, when writing, a block is 
sent to the storage medium each time a record is transmitted, 
rather than only when the next record to be transmitted will 
not fit in the current block. 

Variable length blocks each consisting of one record, 
transmitted as a vector. Can be used to read data in any 
other format, so long as BLKSIZE is large enough. 



Figure 10: Parameters Related to Format 



Format 

The value of the parameter RECFM is recorded as part of the data 
set label when a data set is created. Each time the data set is 
subsequently opened, this value is used as the default. If an explicit 
value is given in the command it overrides the stored value, at least 
for the duration of the access, and replaces it if the access is for 
sequential writing. 

When reading blocked records with RECFM=U, each block is returned 
as a single record, regardless of the structure originally imposed by 
blocking. 

Any RECFM value except u can be extended by the letters A or M 
(for example, VBA or VBM) , which means that the first character in the 
record is to be treated by the system output writers as a device control 
character according to the ANSI or IBM code convention given in Figure 
11. 
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Record Length 

The parameter LRECL sets the record size, expressed in bytes, in 
case of fixed format records, and indicates a maximum size for variable 
format records. 

The four-byte length indicator automatically prefixed to the 
record in writing with recfm=V or vb includes itself in its value, and 
the record length is therefore four more than the length of the data to 
be stored. The latter is often referred to as the logical record 
length . — 3 

Block Size 

The general considerations that go into a choice of block size 
involve a balance between the need to limit buffer areas in the computer 
memory and the need to conserve external storage space by the use of 
larger blocks or the need to reduce retrieval time by having more 
records per block. 

The block size parameter, always has the form BLKSIZE=n, where n is 
expressed in bytes. Except for fixed formats it indicates an upper 
limit. When reading with RECFMxU , oversize records are truncated to the 
indicated block size. 



ACTION (1) 


CONTROL CHARACTERS (2) 


A-ANSI M-MACHINE 


For C0DE=C 

use OAV 
indexed by 


For C0DE=E 

use APL 
character 


For CODE-C 

use UAV 
indexed by 


Suppress line spacing 
Space one line 
Space two lines 
Space three lines 
Skip to channel 1 
Skip to channel 2 
Skip to channel 3 
Skip to channel 4 
Skip to channel 5 
Skip to channel 6 
Skip to channel 7 
Skip to channel 8 
Skip to channel 9 
Skip to channel 10 
Skip to channel 11 
Skip to channel 12 


78 (5) 

6 4 
240 

96 
241 
242 
243 
244 
245 
246 
247 
248 
249 
193 
194 
195 


+ 
space 



l 

2 
3 
4 

5 
6 
7 
8 
9 
A 
B 

c 


1 (5) 

9 

17 

25 
137 
145 
153 
161 
169 
177 
185 
193 
2 01 
209 
217 
225 


Select punch pocket 1 (3) 
Select punch pocket 1, CB (4) 
Select punch pocket 2 
Select punch pocket 2, CB 


229 
230 


V 
W 


1 
33 

65 
97 


Notes: 1. Action takes place before line is printed for ANSI, 
and after line is printed for machine encodinq. 

2. Characters other than these default to space one line 
or select punch pocket 1, as appropriate. 

3. Characters shown for 2520 Punch. See OS/VS 
references for others. 

4. CB: column binary. 

5. Zero-origin indices. 



Figure 1 1 : Unit Record Output Control Characters 
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Figure 12 shows the relationship of block size to track length for 
three direct access devices. Formulas for these values under different 
conditions can be found in the OS/VS reference publications. 



Device 


2311+ 


3330 


3340 


Bytes/Track 
(Unit Size) 

Tracks/Cylinder 

Bytes/Cylinder 

Cylinders/Volume 

Bytes /Volume 
(millions) 


7294 

20 

145,880 
200 
29 


13 ,030 

19 

247 ,570 
4Q4 
X 00 


8368 

12 

100,416 
3 4 8/696 
3 5/70 



Figure 12. Disk Storage Device Capacities 



SPACE ALLOCATION (SPACE) 

Direct access devices are comprised of storage units called 
tracks ; the storage capacity of a track varies with the type of device, 
for example, the maximum on a 2314 disk is 7294 bytes per track, but on 
a 3330 is 13,030. Space is always allocated in increments of tracks - 
that is, one or more whole tracks are allocated even though a portion of 
the last track may not be needed. Each connected piece of allocated 
storage is called an extent . 

The storage space on each track may be subdivided into one or more 
blocks (or physical records ) , separated by inter-record gaps. The size 
of the gaps varies with the type of device and in some cases with the 
size and number of blocks stored on the track. 

The SPACE parameter has a compound value which in its complete 
form has the appearance £7MCff=(1000, (100 ,2Q ,13 ) ) . The fields give, in 
order, a nominal block size, the number of blocks to be allocated to the 
data set initially, an incremental number of blocks for secondary 
allocation if required (up to a maximum of 15 times), and the number of 
records that are to be contained in the directory of a partitioned data 
set. The parameter can be limited to two or three fields with the 
following alternatives: 

5Pi4(7B , = (10 00,(10 0,20) ) - normal form for non-partitioned data set 

SPACE- ( 1000 ,(1Q0) ) - simplest form of parameter specification, 
disallows secondary allocations 

SiMC#=( 10 00,(10 0, ,13) ) - as above, but with a directory space 
requirement specified 

The number of units (tracks) of space allocated is approximated 
from the block-size field B and the number of blocks N according to the 
expression [N*lTLrB, where TL is track length for the device. A more 
exact computation makes use of a table such as Figure 1 3 . 

Figure 13 shows the possible division of a single track into 
blocks of storage space for the 2314, 3330, and 3340 disk devices. For 
each device, one column shows the maximum number of bytes that each 
block could contain if the track contained from one to 30 blocks; a 
second column shows the percentage of the track that would actually be 
used for storage of data, the rest being lost to inter-record gaps. 
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Blocks 


2314 


33 


30 


3340 


Bytes 


% 


Bytes 


% 


Bytes 


% 


per 


per 


Utili- 


per 


Utili- 


per 


Utili- 


Track 


Block 


zation 


Block 


zation 


Block 


zation 
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7294 


100 


13030 


100 


8368 


100 


2 


3520 


97 


6447 


99 


4100 


98 


3 


2298 


95 


4253 


98 


2678 


96 
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1693 


93 


3156 


97 


1966 


94 
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1332 


91 
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2059 


95 
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90 
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88 
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93 


899 


86 
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781 


84 
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615 


84 
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82 


11 
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83 
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90 


608 


80 


12 


496 


82 


962 


89 


544 


78 


13 


450 


80 


877 


87 


489 


76 


14 


411 


79 


805 


86 


442 


74 


15 


377 
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742 


85 


402 


72 
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76 
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84 


366 
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17 


321 
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639 


83 


335 
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74 


596 
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276 


72 
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81 


282 
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258 


71 


523 
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259 


62 
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241 


69 
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79 


239 


60 


22 


226 


68 


463 


78 


220 


58 


23 


211 


67 


437 


77 


204 


56 


24 


199 


65 


413 


76 


188 


54 


25 


187 


64 


391 


75 


174 


52 


26 


176 


63 


371 


74 


161 


50 


27 


166 


61 


352 


73 


149 


48 


28 


157 


60 


335 


72 


137 


46 


29 


148 


59 


318 


71 


127 


44 


30 


139 


57 


303 


70 


117 


42 



Figure 13. Track Length and Block Size 

TAPE DATA SETS (DEN, LABEL, TRTCH) 

It is often necessary to. introduce into APLSV data from other 
sources, such as a physical-data collection device or an existing 
time-series data base. TSIO permits the direct use of magnetic tape 
devices for this purpose. The prospective tape user must consult the 
system operator to schedule use of a magnetic tape drive. When 
submitting a magnetic tape reel, the user should ensure that the tape is 
clearly identified, by its volume serial and APL user's account number, 
since these will be displayed to the operator from TSIO. A tape having 
standard labels can be read by a command such as: 

CTL+ ' SR DSN=NNN , C0DE=C , UNIT= 2 400, VOLUME^ABCO 2P ' 

where the volume serial number , used in the VOLUME parameter, and the 
data set name must match those recorded on the tape. 

The standard data set label carries information on format, block 
size, and record length, so that the corresponding parameters need not 
be given explicitly. (The manual "OS/VS Tape Labels" CGC2 6-3795) gives 
detailed information about the content and use of standard magnetic tape 
labels.) The use of code c assures that a complete image of the record 
will be transmitted to the workspace without loss of information, but if 
a code other than C is known to be appropriate for the data, its use may 
reduce the requirement for subsequent processing. 
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The UNIT parameter must be given explicitly, since the default 
value is a subset of the direct access devices at the installation. _ The 
value for this parameter will vary with the installation, but 2400 is 
often used as a generic designation for tape drives. 

Tapes without labels, or with non-standard labels, can also be 
read, using variations in the reading command with parameters such as 
LABEL and TRTCH (tape recording technique) . The parameters RECFM, 
LRECL, and BLKSIZE must be given explicitly for tapes without standard 
labels. Some experimentation will usually be required, but this can be 
conducted at the APL terminal. 

The reading and writing of data sets on tapes involves the use of 
density , label , and tape recording technique parameters. The density 
determines the recording density (bytes per inch) and applies to 
seven-track and nine-track tapes as follows: 

HEN Track Density 

~0 7 200 

1 7 556 

2 7 800 

2 9 800 

3 9 1600 
i+ 9 6250 

The default value is the largest applicable to the particular tape unit 
allocated. 

The LABEL values SL, NL, and BLP denote standard labels, no 
labels, and bypass label processing, respectively. The values may be 
prefaced by data set sequence numbers, as in LABEL=( 12 ,NL) , or may 
appear with the number omitted, as in LABEL-(,NL). An omitted number 
implies l, that is, the first data set on the tape. See OS/VS Tape 
Labels (GC26-3795) for further information. 

The TRTCH parameter, which applies to 7-track tapes, specifies the 
type of parity check (odd or even) applied in reading or recording each 
byte, and the application of the data conversion feature, or EBCDIC-BCD 
translation, as follows: 



TRTCH 


Parity 


Translation 


Conversion 


C 


Odd 


None 


Yes 


E 


Even 


None 


No 


T (write) 


Odd 


EBCDIC-*BCD 


No 


r(read) 


Odd 


BCD-j-EBCDIC 


No 


ET (write) 


Even 


EBCDIC-+BCD 


No 


ET (read) 


Even 


BCD+EBCDIC 


No 



The data conversion feature provides the encoding of 8-bit characters in 
the 6-bit configuration of a 7-track tape, using four frames for three 
characters. The default case (when TRTCH is not specified) provides odd 
parity, no translation, and no conversion. 

Detailed information about 7-track tape drives may be found in the 
System/370 Component Description publication for the tape unit to be 
used. 

SYSTEM LEVEL OPERATIONS lEXPDT , KE1LEN , SYSOUT) 

System level users may employ four additional data management 
commands (CATALOG, UNCATALOG, READVTOC , and MSG\ , and two further- 
parameters (EXPDT and KEYLEN) . They must, however, provide a fully 
qualified OS/VS data set name for all operations, and explicitly catalog 
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and uncatalog their data sets whose names do not begin with TSIO, unless 
the name is given with an associated account number, as in 

DSN=H527 3 DATA. 

A catalog operation command relates a data set name to a volume 
and has the form: 

CTL*-' CATALOG DSN=ABC . DE ,VOLUME=QRS012 ,VNIT=3 330 ' 

The user should be careful to use only device class designations in the 
unit field (3330, 2314, and so forth) . 

The uncatalog operation requires only a data set name: 

CTL-*-' UNCATALOG DSN-OBSO .LETE X 

A direct access volume carries a table of contents which comprises 
the labels for the data sets it contains. This can be read by the 
following command form: 

CTL+'READVTOC V0LUME=QRS012 ,C0DE=C 

after which the VTOC is treated as a sequential file. The publication 
QS/ VS System Data Areas (VS1 : SY28-0605; VS2 : SYB8-0606) gives a 
complete description of the VTOC. 

A system level user can send a message to the OS/VS console by 
using the form 

CTL+'MSG PLEASE DO SOMETHING FOR ME* 

The next reference to CTL reads the operator's reply, and CTL is 
returned to command state. If the operator does not reply the variable 
CTL remains unusable unless retracted and reshared. 

Date Protection 

An important data set can be protected against deletion or 
over-writing by associating an expiration date with it. The EXPDT 
parameter specifies the date before which the data set can not be 
deleted or overwritten without operator intervention. The form is 
EXPDT=7500l, which has a two-digit year number and a three-digit day 
number. It can be used in a sequential write command with DISP=NEW. 

Key_ Length 

The data sets created by TSIO users are recorded without keys, 
although the use of keyed records is an option in OS/VS. To provide 
access to existing direct access data sets that may be keyed, system 
level users can use the KEYLEN parameter to read such data sets. The 
key will appear as the first KEYLEN bytes of the record. 

The parameter specifies the length n, in bytes, of the keys used 
in the data set, and has the form KEYLEN -n. The largest value allowed 
for this parameter is 255. 

Sysout Data Sets 

The SYSOUT parameter identifies a temporary data set and enqueues 
it for recording on a unit of the class specified by the single 
character associated with it. The associated character varies from 
installation to installation, but the use of SYS0UT=A for the high-speed 
printer and of SYS0UT=B for the card punch is common practice. 
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In addition to the class character, the SYSOUT parameter may give 
a program name and form number, as follows: 

SYS0UT=(A .PRINT, An 2 ) 
SYS0UT=(A, PRINT,) 
SYS0UT=(A,,AR2) 

The program na,me identifies the program from the system library to be 
used instead of the standard system output writer. The form number 
(limited to at most four alphanumeric characters) specifies the paper or 
card form to be used in printing or punching respectively. 

Following the opening of the data set by, say: 

CTL+'SW SYS0UT=A' 
CTL 


CTL is specified successively by each line of printed output, until the 
entire text has been transmitted. Since an empty vector would signal 
the close of the data set, blank lines must be transmitted as consisting 
of at least one space. After the transmission, the data set must be 
closed before any actual output can take place: 

CTL-*- ' ' 
CTL 


Jobs may be submitted for execution to the operating system by a 
system level user, or via an IC command that accesses a command data set 
of a system level user. A job is given by a data set with parameters 
SYSOUT=U,INTRDR) , where A stands for a job class and INTRDR stands for 
an installation- or system-defined reader procedure. The records of the 
data set are card images. The job is submitted for execution when the 
data set is closed. 
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SECTION 4: USE OF DISTRIBUTED WOR KS PACES 

Groups of related workspaces are described under each heading 
below. In general, if there is no workspace of instructions associated 
with the application workspace, the instructions will be contained in 
either a function or a variable DESCRIBE within the workspace. As 
distributed, these workspaces are in library i. 

ARRAY FILE 

The workspace APLFILE, which makes use of TSIO, provides functions 
for storing and retrieving APL arrays in indexed files outside the 
workspace. The arrays may differ in size, and may be of any length that 
will fit within the total space allocated, including lengths that span 
several tracks of the storage device. The user stores or retrieves an 
array by means of the functions SET and GET, specifying in their 
arguments the name of the file and an index number. For example, the 
instruction: 

( 'FILE' AT I) SET X 

stores the array X as the Ith array in a file called FILE. Similarly, 
the Ith array of the file called FILE is retrieved by the expression: 

GET 'FILE* AT I 

When repeated references are made to the same file, instructions after 
the first need refer only to the index number; the file name is presumed 
to be the one last named. The foregoing instructions become: 

I SET X and GET I respectively. 

Other functions supplied in the workspace may be used to create a 
new file, to initiate or terminate use of a file, to delete an entire 
file or to erase indicated members within a file. To accomodate _ files 
shared between several users, the file includes a record of the identity 
of the last user to update it and the time at which updating occurred. 

NUMERIC DATA CONVERSION BETWEEN APLSV AND S/ 370 

The workspace CONVERSION provides functions to convert to and from 
the number representations used by APLSV and alternative schemes used by 
other programs. Each of the conversion functions has a two-letter name 
of which the last letter is either I or (indicating whether data is to 
be transferred into or out of an APLSV environment) and starting with 
one of the letters C, F, I, or B (indicating whether the data format 
outside APLSV is character, floating point, integer, or Boolean) . 

In addition, the workspace contains the variables CD, FD,_ID, and 
BD , each of which provides a description of the pair of conversion 
functions for characters, floating point, integers, or Boolean, 
respectively . 

LINE EDITING 

MEDIT 
SEDIT 
FEDIT 
HOWEDITS 

Three related workspaces are provided to facilitate editing text 
material that is organized into lines; these are useful in preparing 
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text that will subsequently be treated as a program to be submitted to a 
language processor outside APLSV (such as an assembler or compiler) or 
as an APL function definition. Functions are provided to display, 
delete, or edit the existing lines of a program, and to append or insert 
new lines. 

The workspaces MEDIT and SEDIT (for "matrix edit" and "string 
edit") are functionally identical, but differ in the way in which the 
stored program is represented: as a single string containing no blanks, 
or as a matrix. MEDIT, using matrix representation, is faster but 
requires more space than SEDIT. 

The workspace FEDIT (for "file edit"), which makes use of TSIO, 
contains additional functions intended to read a text (that is, a 
program listing) from a data-set outside APLSV, or return the resulting 
program from the APL workspace to an external data-set, for storage or 
for subsequent submission to an external language processor. 

Instructions for use of the three line-editing workspaces are 
contained in the workspace HOWEDITS. 

TSIO UTILITY 

The workspace TSIO contains functions intended to facilitate the 
use of TSIO to manage files and to transmit data between files and the 
APL workspace. It also contains functions for creating, manipulating, 
and displaying the contents of command data sets, that is, of secured 
data sets intended for control of indirect command execution. 

The function TRY takes as its left argument the names of the 
variables shared with TSIO, and as its right argument the TSIO command 
to be executed. The function reports error conditions as appropriate, 
or may be embedded in a user function containing provision to branch, 
exit, retry, etc. as appropriate. 

The function CHK is used to interpret the return values of TSIO 
control variables. It is called by TRY to interpret the return from 
TSIO commands, and may also be embedded in user-written functions for 
data transfer. It permits the user (at his option) to have an error 
message printed, to branch to another statement in the user's function, 
or to suspend execution for debugging. The workspace contains tables 
for interpreting TSIO return codes, and provision to point to the 
defective portion of a TSIO command. 

FORMATTING NUMERIC DATA 

The workspace FORMAT contains the definition of the function FMT , 
used to format numeric data. The left argument is a character string 
depicting a sample output, including non-numeric text or decorations 
both between and within the numeric fields, and indicating characters 
that will mark negative values. These permit the user to insert commas, 
to manage leading or trailing zeros, or to select his own symbol or 
notation for negative values . 

The result of FMT is an array in which each line reproduces the 
picture provided in the left argument, substituting appropriate numeric 
characters for those in the sample, and including embedded decorations 
and the negative indicators where needed. 

This function may be used as a convenience in generating 
specialized formats beyond those available from the primitive format 
function t. Several illustrative examples are provided in the 
workspace. 
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SUBSTITUTE DEFINITIONS FOR WORKSPAC E FUNCTIONS 

Earlier APL systems included a workspace WSFNS containing the 
locked definitions of several functions useful in controlling certain 
workspace parameters such as the printing precision, printing width, or 
index origin. These were implemented using i (I-beam) functions, which 
in APLSV are replaced by system variables with names such as DPP for 
printing precision, Qio for index origin, and so on. All new user 
functions should make use of the system variables for this purpose. 

However, programs brought into APLSV but originating in older 
systems may include functions from the workspace functions formerly 
distributed. These will no longer work. To facilitate conversion of 
those old workspaces , the new workspace WSFNS contains definitions 
having the same name and effect as the former set, but now defined in 
terms of system variables. Copying the workspace WSFNS into the old 
workspace will replace the former workspace functions with the new ones. 
The functions affected are: DELAY , DIGITS, ORIGIN, SETFUZZ, SETLINK, 
and WIDTH. 

NOTICE OF SYSTEM CHANGES AND SCHEDULES 

The workspace NEWS permits users to display notices regarding the 
system operation posted after the date they indicate. Users may also 
obtain a brief summary of the notices and then indicate which they wish 
to see in full. 

The workspace contains functions that assist the system managers 
to insert or revise the notices displayed. 

The NEWS workspace distributed with APLSV is initialized to 
contain a description of the new features of APLSV. 

PLOTTING AND FORMATTING FUNCTIONS 

The workspace PLOTFORMAT contains defined functions useful in 
formatting numeric data and in constructing graphs or histograms at the 
terminal. Functions have been redesigned to use new features of APLSV, 
and will generally be more efficient than APL/360 counterparts but less 
efficient than the direct use of new primitive functions. More 
comprehensive functions for output display are provided by the 
formatting workspace described above, and by the plotting functions 
contained in FDP 5798-AGL, "Graphs and Histograms in APL." 

INSTRUCTIONAL WORKSPACES 

APLCOURSE 
ADVANCEDEX 
TYPEDRILL 
SBIC 

The workspace APLCOURSE contains two functions which generate 
expressions which the user is asked to evaluate. They report his 
success, supply correct answers on request, and keep a record of his 
score. The function EASYDRILL limits the problems posed, but is 
otherwise the same as the function TEACH. 

The workspace ADVANCEDEX contains the definitions of illustrative 
functions for a number of applications, including conversion of number 
representations, data entry, string matching, the evaluations of 
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polynomials, finding roots of polynomials, permutations, combinations, 
matrix inversion, and so on. Each function is accompanied by a 
character vector whose name consists of the letter D followed by the 
name of the function. When displayed, these provide a description and 
discussion of the programming examples. 

It should be noted that some of the examples have been made 
obsolete by extensions to APL. For instance the discussion of matrix 
inversion, while valid, duplicates the effect of the primitive function 

@. 

The workspace TIPEDEILL permits a student of typing to enter a 
typewriter keyboard exercise, and records the speed and accuracy with 
which he is able to repeat it. 

The workspace SBIC contains a model set of functions to perform 
sales, billing and inventory control. Their use and limitations are 
described in the APL Language Manual (GC26-3847) . 
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A, code parameter value, 20 21 23 

24. 
A, format parameter suffix, 20 21 
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access, to APL system, 1. 
ACCESS, TSIO level discriminant, 
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ALLOCATION FAILED, 13. 
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conversion, 34. 
append, further records to file, 

15 17 20 21 23. 
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5. 
array file, workspace, 32. 
associative function, scan of, 4 

5. 
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atomic vector, 3. 
attribute, data set, 10. 
authorization table, 18. 
authorization, of APL account, 2. 
authorization, of use of TSIO, 17. 
auxiliary processor, 
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B, code parameter value, 20 21 23. 
backspace, 3. 



BCD-EBCDIC conversion, seven- track 

tape, 29. 
billing, SBIC workspace, 34 35. 
blank line, in SYSOUT data set, 

31. 
BLKSIZE, parameter, 11 14 17 20 21 

24 26 28. 
BLKSIZE ERROR, 12. 
block, file, 9. 
block size, 11 14 17 20 21 24 26 

28. 
blocked record, 25. 
BLP, parameter value, 21 29. 
boolean, conversion, 32. 
boolean, data type, 3 20 21 23 32. 
boolean, storage required, 3. 
branch, on TSIO error, 33. 
buffer size, 26. 
bypass label processing, 29. 



C, code parameter value, 20 21 23 

26 28. 
cancellation of hold, 19. 
capacity, storage, 27. 
card eject, MCST, 3. 
card punch, 30. 
carrier return, 3. 
catalog, 11 21 22 29 30. 
CATALOG, TSIO command, 11 29 30. 
CATALOG FAILED, 13. 
channel skip, output control, 26. 
character, APL internal 

representations, 2 3 20 21 23 

24 26 28. 
character, conversion, 32. 
character, floating point, 32. 
character, storage required, 2. 
character conversion, APL to 

EBCDIC, 2 20 21 22 24 26 32. 
charges, APL use, 2. 
class, of device, 23 30. 
clear workspace, 2 5. 
closing, data set, 9 10 14 23 31. 
CODE, parameter, 20 21 23 24 28. 
colon, in sign-on command, 2. 
column binary, output control, 26. 
comma, in TSIO command, 11. 
comma, within formatted number 

display, 33. 
command, APL system, 6. 
command data set, 18 33. 
command mode, TSIO, 10 14. 
communication, commands for, 6. 
comparison tolerance, value in 

clear workspace, 5. 
compound name, data set, 22. 
conflicting use of shared data 

set, 19. 



INDEX 



37 



continuation, of display line in 

excess of printing width, 4. 
CONTINUE, command, 2. 
CONTINUE, workspace, 2. 
control, access, 10 16. 
CONTROL VARIABLE IN USE, 12. 
control variable, TSIO, 9 10 11 12 

13 14 16 33. 
control vector, 10 16. 
COPY , command , 2 . 
creation, of new data set, 14 15 

22 32. 
CTL, name prefix for variable 

shared with TSIO, 9 16. 
CTL DOMAIN ERROR, 13. 
cylinder size, 27. 



D 



DAT, name prefix for variable 

shared with TSIO, 9 16. 
DAT VARIABLE REQUIRED, 13. 
data conversion, between APLSV and 

S/370, 21 22 24 32. 
data conversion, seven- track tape, 

29. 
DATA LENGTH ERROR, 13. 
DATA RANK ERROR, 13. 
data set, 9 10. 
data set, command, 18. 
data set, creation, 14 15 22 32. 
data set, format, 24. 
data set, identification, 5 12 14 

20 21 22. 
data set, label, 19 25. 
data set, location, 22. 
data set, non-APL, 21 22 24 32. 
data set, organization, 17. 
data set, reserved, 18 22 33. 
data set, shared, 18 19. 
data set, SYSOUT, 30. 
DATA SET FULL, 13. 
DATA SET IN USE, 12. 
data transfer mode, 10 14. 
DATA TYPE ERROR, 13. 
data variable, TSIO, 9 16. 
DATASET NOT FOUND, 12. 
date, 2. 

date protection, 30. 
day number, 30. 
DD CARD MISSING, 13. 
debugging, programs using TSIO, 

33.. 
decimal form, entry and display of 

numbers, 4. 
decoration, in formatted numbers, 

33,. 
default, parameter values, 20 21 

23. 
definition, function, 8. 
delay, 6. 
DELAY, substitute workspace 

function, 34. 
delete, 32. 



DELETE, TSIO command, 10 20 21. 

deletion, statement, 8. 

DEN, parameter, 20 21. 

density, tape recording, 20 21 28. 

DESCRIBE, variable in distributed 

workspaces, 32. 
device, allocation, 12 17 20 21 22 

23 29. 
device, class, 23 30. 
DEVICE, TSIO level discriminant, 

17. 
DIGITS, command, 8. 
DIGITS, substitute workspace 

function, 34. 
direct access- storage device, 17 

27. 
directory, partitioned data set, 

27. 
DIRECTORY ERROR, 13. 
discriminant, of TSIO level, 17. 
disk pack, identification, 23 27 

28. 
DISP, parameter, 11 14 15 17 18 20 

21 23 30. 
DISP ERROR, 12. 
display, error message from TSIO, 

33. 
display, numeric, 8. 
disposition, data set, 11 14 15 17 

18 20 21 23 30. 
domain, primitive functions, 5. 
drill, in evaluating APL 

expressions, 34. 
DSN, parameter, 5 12 14 20 21 22. 
DSNAME ERROR, 12. 
DUPLICATE NAME, 12. 
duplication of local names, 8. 



E 



E, code parameter value, 2 20 21 

24 26. 
EBCDIC, translation between APL 

character codes and, 2 20 21 22 

24 26 32. 
EBCDIC-BCD conversion, seven- track 

tape, 29. 
editing, APL function, 1. 
editing, programs written in 

languages other than APL, 33. 
editing, suspended APL function, 

8. 
editing, text organized by lines, 

33. 
empty vector , 9 14. 
end of file, 9 10. 
enqueue, for output writer, 30. 
environment, commands that affect, 

6. 
erase, records within APLFILE, 32. 
error messages, TSIO commands, 12. 
error messages, TSIO data 

transfer, 13. 
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error report, from TSIO, as return 

value of shared variable, 10 12 

13 33. 
exclusive hold, data set, 19. 
exclusive use, data set, 18. 
exercises, in evaluating APL 

expressions, 34. 
EXPDT, parameter, 20 21 30. 
expiration date, 20 21 30. 
exponential, 6. 
extension, of data set, 14. 
extent, direct access storage 

device, 27. 
external language processor, 33. 



F 



F, code parameter value, 2 20 21. 
F, format parameter value, 15 20 

21 24 25, 
factorial, 6. 
failure, indicated by return code, 

11. 
FB, format parameter value, 20 21 

25. 
FBS, format parameter value, 21 

25. 
FILE INDEX ERROR, 13. 
floating point, conversion, 32. 
floating point, range of 

representable values, 3. 
floating point, representation, 2 

3 5 20 21 32. 
floating point, storage required, 

3 5. 
form number, SYSOUT data set, 31. 
format, primitive function, 3. 
format, record, file parameter, 15 

17 20 21 22 24 26 28. 
FORMAT, workspace, 33. 
fully qualified name, 22 29. 
function, suspended, 8. 
function definition, 8. 



gap, inter-record, 27. 

GET, function within APLFILE, 32, 

graphs, workspace for, 34. 



horizontal tab, 3. 



I, code parameter value, 20 21 23. 
IC, TSIO command, 11. 
ICDESCRIBE, in TSIO workspace, 18. 
identification, auxiliary 
9. 

2 



user, 



19. 



processor, 6 
identification, 
idle, 3. 
immediate hold, 
IMPARSIBLE COMMAND, 12. 
INCORRECT COMMAND, 2 8. 
INCORRECT SIGN ON, 2. 
incremental block size, 



17. 



27. 



indent, of continuation display, 

4. 
index origin, 2 8 16. 
index origin, value in clear 

workspace, 5. 
indexed access, 9 11 15 16 32. 
indexed access to variable length 

records, 32. 
indexed read, file via TSIO, 11. 
indexed read-write, file via TSIO, 

9 11 15 16 20 21 . 
indexing, 6. 

indirect command, 11 33. 
inner product, 6. 
instructional workspaces, 34. 
integer, conversion, 32. 
integer, range of representable 

values, 3. 
integer, representation, 3 5 20 21 

23 32. 
integer, storage required, 3 5. 
interlock, 10 14 16. 
internal representations, APL, 3. 
interpreter, APL, 1. 
inter-record gap, 27. 
inventory, SBIC workspace, 34 35. 
IR, TSIO command, 11 15 20 21. 
IRW, TSIO command, 9 11 15 16 20 

21. 
I-beam functions, 34. 
I/O BUFFERS FULL, 12. 
I/O ERROR, 13. 



H 



header, function, 8. 

header, variable, when stored in 

file, 9 23. 
high speed I/O, 9 30. 
high speed printer, 30. 
histograms, workspace for, 34. 
hold, cancellation of, 19. 
hold, exclusive, 19. 
hold, immediate, 19. 
hold, shared, 19. 



JCL, 21. 

Job Control Language, 21. 



K 



key length, 21 29 30. 

keyed records, 30. 

KEYLEN, parameter, 21 29 30. 
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label, data set, 19 20 21 22 28 

29. 
LABEL, parameter, 21 29. 
label,, tape, 28. 
laminate , 6 . 

Language Manual , APL , 1 . 
language processor, 33. 
latent expression, 2. 
latent expression, value in clear 

workspace, 5. 
leading zeros, in formatted 

numbers, 33. 
LEAVE,, parameter value, 23. 
level, access to TSIO, 17. 
libraries, private and public, in 

APL system, 6. 
line editing, workspace 

distributed with APLSV, 32. 
line spacing, output control, 26. 
linefeed, 3. 
LOAD , command , 2 . 
local names, duplication of, 8. 
LRECL, paramter, 17 20 21 24 26. 
LRECL ERROR, 12. 



M 



M, format parameter suffix, 20 21 

25 26. 
machine encoding, output line 

control, 26. 
magnetic card Selectric 

typewriter, CMCST) , 3. 
matrix edit, 33. 
MEMBER NOT FOUND, 12. 
message, APL operator, 2 7. 
message, between APL users, 7. 
message, control of delivery, 7. 
message, to OS/VS operator, 30. 
MOD, parameter value, 15 17 20 21 

23. 
mode, of TSIO control variable, 

10. 
MSG, APL command, 7. 
MSG, TSIO command, 11 29. 
MSG OFF, command, 7. 
MSG ON, command, 7. 
MSGN , command , 7 . 



N 



name, APL object, 5 6. 

name, data set, 5 12 14 20 21 22, 

name, of user, 2 6. 

name, qualified, 22 29. 

name, surrogate, 5 9 15. 

name , workspace , 5 . 

names , number of in workspace , 6 , 

national characters, 24. 

negative account number, 18 22. 



negative sign, optional, provided 

by FORMAT workspace, 33. 
NEW, parameter value, 14 20 21 30. 
NEWNAME, parameter, 21. 
NEWNAME ERROR, 12. 
NEWS, APL function, 34. 
nine-track tape, 29. 
NL, parameter value, 21 29. 
non-APL data, 22. 
non-APL language processor, 33. 
non-standard label, 29. 
number, user account, 2. 
NUMBER LOCKED OUT, 2. 
number representation, conversion, 

APLSV and S/370, 32. 
numbers, form of entry and 

display, 4. 
numbers, how represented by APL 

system, 3. 
numeric display, 8. 



OLD, parameter value, 15 20 21. 
OPEN FAILED, 13. 
opening, data set, 9 16 25 31. 
operating system, 9. 
operation code, indexed 

read-write, 16. 
operator, system, 18 23 30. 
OPR, command, 7. 
OPRN , command , 7 . 
optimum record length, 27. 
order of execution, of scan and 

reduction, 4 5. 
organization, data set, 17. 
ORIGIN, command, 8. 
origin, index, 8. 
ORIGIN, substitute workspace 

function, 34. 
output, high speed, 9„ 



parameters, data set, 2 5 10 20 21 

23 24 26 27 28. 
parameters, TSIO command, 19. 
parentheses, in TSIO command, 11. 
parity, seven-track tape, 29. 
partitioned data set, 17 22 27. 
password, user account, 2. 
PDS DIRECTORY FULL, 12. 
period, in data set name, 22. 
physical record, 27. 
picture, to control formatting of 

numbers, 33. 
PLOTFORMAT, workspace, 34. 
plotting, workspace for, 34. 
port, 2 7. 
PORT, command, 7. 
PORTS, command, 7. 
position controls, data set 

access, 22. 
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precision, internal, and order of 

execution, 4 5. 
precision, printing, 3 4 8. 
primitive functions, domain of, 5 

6. 
printer, high speed, 30. 
printing precision, 3 4 8. 
printing precision, value in clear 

workspace, 5. 
printing width, 4 8. 
printing width, value in clear 

workspace, 5. 
privacy, 2 9 10 17 18 30 33. 
processor, identification, 6 9. 
program name, SYSOUT data set, 31. 
punch pocket select, output 

control, 26. 



qualifier, data set name, 22 29. 
queuing, TSIO, 19. 
quota, interface, 17. 



random link, value in clear 

workspace, 5. 
rank, maximum, 4. 
rank, of stored array, 4. 
read, file, via TSIO, 10. 
READVTOC , JCL command , 21. 
READVTOC, TSIO command, 11 29 30. 
real, see floating point. 
RECFM, parameter, 15 17 20 21 24 

26. 
RECFM ERROR, 12. 
record, file, 9. 
record, physical, 27. 
record format, 9 15 17 20 21 24 25 

26. 
record length, 13 17 20 21 24 26 

28. 
record length, optimum, 27. 
recording density, 20 21 28. 
recording technique, 20 21 28 29. 
reduction, operator, order of 

execution, 4 5. 
RENAME, TSIO command, 10 11 2 21. 
representation, conversion between 

APLSV and S/370, 32. 
representation, number and 

character, in APLSV system, 3. 
representation, number and 

character, in files, 23. 
REREAD, parameter value, 23. 
reserved data set, 18 22 33. 
reshape, 6. 

response code, TSIO, 11. 
RESTRICTED COMMAND, 12. 
retraction, of sharing of TSIO 
| control variable, 10 19. 
retry, following TSIO error, 33. 



return code, TSIO, 10. 

return value, variable shared with 

TSIO, 33. 
reverse half linefeed, MCST, 3. 
rewriting, of file via TSIO, 14. 
right parenthesis, in sign-on 

command , 2 . 



sales, billing, inventory control, 

illustrative workspace SBIC, 34 

35. 
SBIC, illustrative workspace, 34 

35. 
scaled form, entry and display of 

numbers, 3 4. 
scan, operator, order of 

execution ,45. 
schedule, function for listing 

APLSV system's, 34. 
secondary allocation, 27. 
secured data set, 18 22 33. 
security, 2 9 10 11 17 18 30 33. 
sequential read, file, via TSIO, 

11 14 17 20 21 . 
sequential write, file, via TSIO, 

10 11 14 17 25. 
SER, parameter, 21. 
serial, 23 28. 

SET, function within APLFILE, 32. 
SETFUZZ, substitute workspace 

function, 34. 
SETLINK, substitute workspace 

function, -34. 
seven- track tape, 29. 
shared access, 18 20 21 23. 
Shared Variable Processor, 1. 
shared variable quota, 17. 
shared variable, access control, 

10 16. 
SHR, parameter value, 18 20 21 23. 
SI DAMAGE, 8. 
sign-on, 2. 

significant digits, 1. 
size of workspace, 6. 
skip, channel, output control, 26. 
SL, parameter value, 21 29. 
I space, conversion to tabs, 5. 
space, output control, 26. 
SPACE, parameter, 20 21 27. 
SPACE, TSIO level discriminant, 

17. 
space allocation, 22. 
spaces, in TSIO command, 11. 
spanned records, 32. 
SR, TSIO command, 11 14 20 21. 
standard label, 28. 
state indicator damage , 8 . 
statement deletion, 1. 
storage capacity, 27. 
storage space, as function of data 

format and encoding, 24. 
storage utilization density, 28. 
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string edit, 33. 

success, indicated by return code, 

11. 
suffix, for name shared with TSIO, 

9. 
suppress line spacing, output 

control, 26. 
surrogate name, 5 9 15. 
suspended function, 8. 
SW, TSIO command, 11 14 15 20 21. 
symbol table, 6. 
synchronization, indexed 

read-write , 16. 
synchronization, TSIO with APL, 

10., 
SYSOUT, parameter, 20 21 30. 
SYSTEM, TSIO level discriminant, 

17. 
system commands , 6 . 
SYSTEM ERROR, 13. 
system level commands, 29. 
system level, TSIO use, 11 22. 
SYSTEM QUEUE ERROR, 13. 
SYSTEM QUEUE FULL, 13. 
system variables, 5. 
system output writer, 30. 



tab , 5 . 

tab, conversion to spaces, 5. 

tab stop position, 5. 

take, 6. 

tape, magnetic, 19 20 21 23 28 29. 

tape label, 28. 

tape recording density, 20 21. 

tape recording technique, 20 21 28 

29. 
temporary data set, 30. 
terminal control characters , 2 . 
termination, data transfer, 10. 
time, 2 32. 
time series data, 28. 
track length, direct access 

device, 27 28. 
track link, MOST, 3. 
trailing zeros, in formatted 

numbers, 33. 
translation, APL to EBCDIC 

characters, 21 22 24 32. 
TRTCH, parameter, 20 21 29. 
TRY, function in TSIO workspace, 

33. 
TSIO, workspace, 18 33. 
TYPEDRILL, workspace, 34. 
typing, functions for practice in, 

34. 



unblocked record, 9 15 20 21 25 

26. 
UNCATALOG, TSIO command, 11 29. 
UNIT, parameter, 17 20 21 22 23 

29. 
UNIT ERROR, 12. 
unlabeled tape, 29. 
update, APLFILE, 32. 
update, with exclusive hold, 19. 
user identification, 2 7 17 18. 
user identification, posted in 

APLFILE, 32. 
utilization, storage, 28. 



V 



V, format parameter value, 20 21 

25 26. 
VARIABLE TOO LARGE, 13. 
variable-length records, indexed 

access, 15. 
VB, format parameter value, 20 21 

25 26. 
VOL, see VOLUME. 
VOL REQUIRED, 12. 

VOLUME, parameter, 17 20 21 22 23. 
VOLUME FULL, 12. 
volume size, 27. 
volume table of contents, 11 29 

30. 
VOLUME UNAVAILABLE, 12. 
VTOC FULL, 13. 



W 



WIDTH, command, 8. 

width, printing, 8. 

WIDTH, substitute workspace 

function, 34. 
workspace, from locked-out 

account, 2. 
workspace, size of, 6. 
workspace functions , substitute 

definitions for program 

converted from APL/360, 34. 
workspaces, distributed with 

APLSV, 32. 
write, indexed, via TSIO, 9 11 15 

16 20 21. 
write, sequential, via TSIO, 10 11 

14 15 20 21. 
WSFNS, workspace containing 

definitions revised from 

APL/360, 34. 



U, format parameter value, 9 15 20 
21 25 26. 



year number, 30, 
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zero, as return code, 11 14. 
zeros, leading or trailing, in 

formatted numbers, 33. 
zero-origin, 2 16. 
zoned decimal, 24. 
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